Stale Values

When I first started using computers in the late 90s, I used two different media players.

For livestreaming, I had RealPlayer:

Screenshot of RealPlayer, a Windows 95 themed media player

RealPlayer was OK, but it didn't really have any personality. To my teenage self, there was a much cooler option available: Winamp.

Screenshot of Winamp, a cool retro-looking media player

Between those early days and now, there have been countless media players, but there's something they've all had in common. Every media player I've ever used has implemented the exact same keyboard shortcut:

The spacebar key will play (or pause) the currently-selected song.

Earlier in this module, we built a simple media player, and I think we should update it to include the spacebar shortcut!

If you'd like, I'd encourage you to spend a couple minutes attempting this problem, but I'll warn you now: It's surprisingly tricky.

Code Playground

import React from 'react';

import { Play, Pause } from 'react-feather';

import VisuallyHidden from './VisuallyHidden';

function MediaPlayer({ src }) {

const [isPlaying, setIsPlaying] = React.useState(false);

const audioRef = React.useRef();

return (

<p>Bvrnout ft. Mia Vaile</p>

</div>

<button

onClick={() => {

if (isPlaying) {

audioRef.current.pause();

} else {

audioRef.current.play();

}

setIsPlaying(!isPlaying);

}}

{isPlaying ? <Pause /> : <Play />}

<VisuallyHidden>Toggle playing</VisuallyHidden>

</button>

<audio

ref={audioRef}

src={src}

onEnded={() => {

setIsPlaying(false);

}}

</div>

);

}

export default MediaPlayer;

Let's talk about it.

Video Summary

To start, I've implemented the standard structure we've been seeing recently:

React.useEffect(() => {
  function handleKeyDown(event) {
    if (event.code === 'Space') {
      // TODO: Play or pause
    }
  }

  window.addEventListener('keydown', handleKeyDown);

  return () => {
    window.removeEventListener('keydown', handleKeyDown);
  };
}, []);

We start our subscription, listening for keydown events, and checking if they've pressed the spacebar key. Our cleanup function unsubscribes from this event. Because we've specified an empty dependency array, this event listener runs for the entire component lifetime.

How do we play or pause the song? Well, we have this chunk of code from earlier:

<button
  onClick={() => {
    if (isPlaying) {
      audioRef.current.pause();
    } else {
      audioRef.current.play();
    }

    setIsPlaying(!isPlaying);
  }}
>

The thing that makes this one a bit tricky is that we actually have two bits of state we need to manage:

The React state, under the isPlaying variable.
The internal DOM audio state, which controls whether or not the song is actually playing.

One option is to create a function that manages both:

function togglePlaying() {
  if (isPlaying) {
    audioRef.current.pause();
  } else {
    audioRef.current.play();
  }

  setIsPlaying(!isPlaying);
}

We'd then call this function both when the user clicks the button, as well as within our handleKeydown method.

There are two issues with this approach, however:

We'd have to add this togglePlaying function to our effect's dependency array, which can introduce performance problems. We'll talk more about this when we cover useMemo and useCallback.
It's too easy to forget to use this function!

To expand on that second point, I can easily imagine another developer or myself not realizing that there are actually two relevant pieces of state.

If we're not super careful, we can wind up in scenarios where the two state variables diverge. Maybe isPlaying is set to true, but the audio isn't playing! These issues are very tough to debug, and I'd like to make it as unlikely as possible.

So, here's my solution: We're going to add a second useEffect hook. This hook has 1 job: to make sure that the audio DOM node's internal state is kept in sync with the isPlaying state variable:

React.useEffect(() => {
  if (isPlaying) {
    audioRef.current.play();
  } else {
    audioRef.current.pause();
  }
}, [isPlaying])

We can then update our button to only toggle the state variable:

<button
  onClick={() => {
    // This work is no longer necessary:
    //
    //   if (isPlaying) {
    //     audioRef.current.pause();
    //   } else {
    //     audioRef.current.play();
    //   }

    setIsPlaying(!isPlaying);
  }}
>

And we can update the isPlaying state within our keydown callback as well:

React.useEffect(() => {
  function handleKeyDown(event) {
    if (event.code === 'Space') {
      setIsPlaying(!isPlaying);
    }
  }

  window.addEventListener('keydown', handleKeyDown);

  return () => {
    window.removeEventListener('keydown', handleKeyDown);
  };
}, []);

Now, when we do this, we get a lint warning:

React Hook React.useEffect has a missing dependency: 'isPlaying'.

The problem with our code is that our effect only runs after the 1st render. It means we only have access to the very first snapshot, where isPlaying is permanently set to false.

Every time the user hits the spacebar key, we call setIsPlaying(!false). This means that the keyboard shortcut can start the song, but it can't stop it.

(In the video, there are graphs that help illustrate this; I'll place them below this summary.)

There are two potential solutions to this problem.

Adding the dependency
Using the callback escape hatch

The first option, adding the dependency, is something we saw in the “Effect Lint Rules” lesson. We add the isPlaying state to the dependency array:

React.useEffect(() => {
  function handleKeyDown(event) {
    if (event.code === 'Space') {
      setIsPlaying(!isPlaying);
    }
  }

  window.addEventListener('keydown', handleKeyDown);

  return () => {
    window.removeEventListener('keydown', handleKeyDown);
  };
}, [isPlaying]);

In this solution, we call our cleanup function and re-run the effect whenever isPlaying changes. It means that we're constantly "refreshing" our keydown callback, so that it always has access to the most recent snapshot.

In this particular scenario, this is no problem at all; it's very quick to add / remove event listeners.

But what if the subscription/unsubscription process was slow? Is there any way to access the freshest value of isPlaying without adding it to the dependency array?

There is: Using the callback escape hatch

Here's what it looks like:

React.useEffect(() => {
  function handleKeyDown(event) {
    if (event.code === 'Space') {
      setIsPlaying(currentIsPlaying => {
        return !currentIsPlaying;
      });
    }
  }

  window.addEventListener('keydown', handleKeyDown);

  return () => {
    window.removeEventListener('keydown', handleKeyDown);
  };
}, []);

When we pass a function to our state-setter function, React will invoke this function for us, and whatever we return becomes the new state.

For example, these two statements have the exact same effect:

setIsPlaying(5);
setIsPlaying(() => { return 5 });

When React invokes this function for us, it provides the current value of the state as an argument. This is the freshest value, plucked straight from the component instance.

With this workaround, we're able to keep a single event handler running for the entire component lifecycle.

Which approach is best? They both work equally well in most situations. There's a hypothetical performance benefit to this approach, but it's negligible in most cases.

It's worth becoming comfortable with both approaches. Once you understand them both, you can pick whichever you like best.

I recommend using currentX as the name for the parameter in the callback function. So if the state variable is count, I'd make the parameter currentCount. I also occasionally use currentValue. The goal is to make clear that we're not referencing the potentially-stale variable from the snapshot.

Here are the graphs from the video:

Missing dependency:

Adding isPlaying as a dependency:

Solving using a callback function:

Solution code (success)

We saw two potential solutions in this video.

Solution 1: Adding the dependency

import React from 'react';
import { Play, Pause } from 'react-feather';

import VisuallyHidden from './VisuallyHidden';

function MediaPlayer({ src }) {
  const [isPlaying, setIsPlaying] = React.useState(false);

  const audioRef = React.useRef();

  React.useEffect(() => {
    function handleKeyDown(event) {
      if (event.code === 'Space') {
        setIsPlaying(!isPlaying);
      }
    }

    window.addEventListener('keydown', handleKeyDown);

    return () => {
      window.removeEventListener('keydown', handleKeyDown);
    };
  }, [isPlaying]);

  React.useEffect(() => {
    if (isPlaying) {
      audioRef.current.play();
    } else {
      audioRef.current.pause();
    }
  }, [isPlaying]);

  return (
    <div className="wrapper">
      <div className="media-player">
        <img alt="" src="https://sandpack-bundler.vercel.app/img/take-it-easy.png" />
        <div className="summary">
          <h2>Take It Easy</h2>
          <p>Bvrnout ft. Mia Vaile</p>
        </div>
        <button
          onClick={() => {
            setIsPlaying(!isPlaying);
          }}
        >
          {isPlaying ? <Pause /> : <Play />}
          <VisuallyHidden>Toggle playing</VisuallyHidden>
        </button>

        <audio
          ref={audioRef}
          src={src}
          onEnded={() => {
            setIsPlaying(false);
          }}
        />
      </div>
    </div>
  );
}

export default MediaPlayer;

Solution 2: Callback form

import React from 'react';
import { Play, Pause } from 'react-feather';

import VisuallyHidden from './VisuallyHidden';

function MediaPlayer({ src }) {
  const [isPlaying, setIsPlaying] = React.useState(false);

  const audioRef = React.useRef();

  React.useEffect(() => {
    function handleKeyDown(event) {
      if (event.code === 'Space') {
        setIsPlaying((currentIsPlaying) => {
          return !currentIsPlaying;
        });
      }
    }

    window.addEventListener('keydown', handleKeyDown);

    return () => {
      window.removeEventListener('keydown', handleKeyDown);
    };
  }, []);

  React.useEffect(() => {
    if (isPlaying) {
      audioRef.current.play();
    } else {
      audioRef.current.pause();
    }
  }, [isPlaying]);

  return (
    <div className="wrapper">
      <div className="media-player">
        <img alt="" src="https://sandpack-bundler.vercel.app/img/take-it-easy.png" />
        <div className="summary">
          <h2>Take It Easy</h2>
          <p>Bvrnout ft. Mia Vaile</p>
        </div>
        <button
          onClick={() => {
            setIsPlaying(!isPlaying);
          }}
        >
          {isPlaying ? <Pause /> : <Play />}
          <VisuallyHidden>Toggle playing</VisuallyHidden>
        </button>

        <audio
          ref={audioRef}
          src={src}
          onEnded={() => {
            setIsPlaying(false);
          }}
        />
      </div>
    </div>
  );
}

export default MediaPlayer;

Event bubbling (info)

In our implementation above, there is a small but pesky bug with the user experience.

It's not related to useEffect or anything we've been talking about in this module, but I wanted to share a quick video on the subject, in case you've tripped over this issue.

Video Summary

There's a UX bug with our implementation: if we focus the button and then press the spacebar key, the song starts and then immediately stops, only producing a fraction of a second of audio.

This happens because of an accessibility feature built into modern browsers: focusing a button and pressing either the Space key or the Enter key will simulate a click on that button, firing any attached onClick handlers.

This is a problem, because it means that both the button onClick and the global keydown callback functions are firing. We wind up flipping isPlaying back and forth at lightspeed.

To solve this problem, we can add the following code to our button:

<button
  onKeyDown={(event) => {
    if (event.code === 'Space') {
      event.stopPropagation();
    }
  }}
  onClick={() => {
    setIsPlaying(!isPlaying);
  }}
>

To understand what's going on here, we need to talk about event bubbling.

When we trigger an event on a DOM node, that event "bubbles" up the tree. A keydown event is triggered on the button, but also on its parent, and its grandparent, and it's great-grandparent…

This is what allows us to register global event listeners! The window object is the top-level element in the DOM, and so all events will eventually bubble to it.

Normally, when we focus the button and press "space", that event triggers on the button, but it also triggers on the window object, and every element in-between. But we can short-circuit this process with event.stopPropagation().

This method ensures that the keydown event stops at this element, and doesn't continue on upwards. This way, the window-level keydown event never sees the event. It counts as a click on the button, and so everything works as if we had clicked the button.

To be clear, this has nothing to do with React. stopPropagation() is part of the DOM, not React. But I wanted to share this method here in case you ran into this issue and mistakenly thought it was an issue with your code.

Here's our final implementation:

Code Playground

import React from 'react';

import { Play, Pause } from 'react-feather';

import VisuallyHidden from './VisuallyHidden';

function MediaPlayer({ src }) {

const [isPlaying, setIsPlaying] = React.useState(false);

const audioRef = React.useRef();

React.useEffect(() => {

function handleKeyDown(event) {

if (event.code === 'Space') {

setIsPlaying((currentIsPlaying) => {

return !currentIsPlaying;

});

}

window.addEventListener('keydown', handleKeyDown);

return () => {

window.removeEventListener('keydown', handleKeyDown);

};

}, []);

React.useEffect(() => {

if (isPlaying) {

The state-setter callback

In the video above, we learned about a new way to set React state. It's an important concept, something we'll be using in the lessons and modules ahead, and so I wanted to cover it in more depth.

So far in this course, we've been calling state-setter functions with the new value:

const [count, setCount] = React.useState(0);

// sets `count` to `100`
setCount(100);

There is an alternative syntax for state updates. If we want, we can pass a callback, and React will invoke that function for us:

// sets `count` to `100`:
setCount(() => {
  return 100;
});

Whatever we return from this function becomes the new value for the state, as if we had passed that value directly.

This is useful because React provides the current value:

setCount((currentCount) => {
  return currentCount + 1;
});

In most cases, this isn't necessary, since we already have access to the count variable. But, when working with effects, it becomes possible for us to lose access to the freshest version of a state variable.

In the video above, we saw an example of how this alternative syntax can be useful:

const [isPlaying, setIsPlaying] = React.useState(false);

React.useEffect(() => {
  function handleKeyDown(event) {
    if (event.code === 'Space') {
      setIsPlaying((currentIsPlaying) => {
        return !currentIsPlaying;
      });
    }
  }

  window.addEventListener('keydown', handleKeyDown);

  return () => {
    window.removeEventListener('keydown', handleKeyDown);
  };

  // No dependency on `isPlaying`!
}, []);

If we try and access isPlaying inside the handleKeyDown callback, that value will be stale, since this effect only runs after the very first mount. By passing a callback function, we pluck the freshest value for this state variable, directly from the component instance.

When to use the callback syntax

Most of the time, we don't need to use the callback syntax. This alternative syntax is only necessary when it's possible for state variables to grow stale.

Stale state variables aren't strictly a useEffect thing. It can also happen with other hooks that have dependency arrays, like useMemo and useCallback. We'll learn about them later in this module.

State variables can also grow stale when we have asynchronous code (eg. a fetch request), since it's possible for components to re-render while that asynchronous code is running.

In practice, however, I'd say that 80-90% of the time that I use the callback syntax, it's because of the situation we've been talking about: I need to access a state variable inside an effect, but I don't want to add it to the dependency array.

Why not always use the callback syntax? (info)

You might be wondering: is there ever a reason not to use the callback syntax? Why not use it in every situation?

For example:

function Counter() {
  const [count, setCount] = React.useState(0);

  return (
    <button
      onClick={() => {
        setCount((currentCount) => currentCount + 1);
      }}
    >
      {count}
    </button>
  )
}

This is a typical “counter” app. There are no effects, no asynchronous code. There's no way for the state to grow stale. But the alternative "callback" syntax still works just fine.

Even though it works, I don't suggest doing this.

For one thing, it's unconventional. If I saw this in a production codebase, I'd wonder if I was missing something, if there was some way for the count state variable to grow stale.

But there's a deeper reason I suggest not using this syntax by default.

When I was a kid, I broke my left leg in 3 places. I had to spend many months in a cast that went from my ankle to my hip. During this time, I used crutches to get around.

When the cast finally came off, I had to go to physiotherapy in order to learn how to walk again.

If you've ever been in a situation like this, you know that this sort of physiotherapy is no fun at all. It's painful and difficult and stressful. I remember wishing I could just stick with the crutches; after months of practice, I had gotten pretty nimble with them!

Why am I telling you all of this? Well, I think that this alternative "callback" syntax can be a kind of crutch. By leaning on the callback syntax, we don't have to worry about this tricky "stale values" stuff.

Ultimately, though, if we want to truly become comfortable with React, we need to understand this stuff. And the only way to build that understanding is by practicing.

So, here's what I suggest: use the default non-callback form by default. When you run into bugs, you can try the callback syntax to see if it helps. If it does, spend a few moments seeing if you can understand why. I promise, with enough practice, this stuff will eventually click.